home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 5
/
Apprentice-Release5.iso
/
Source Code
/
Libraries
/
Sherlock 2.0
/
Mac v2.0 docs
/
Text Docs
/
Mac Installation .txt
< prev
next >
Wrap
Text File
|
1996-04-05
|
12KB
|
316 lines
Installing Sherlock on the Macintosh
This chapter provides step-by-step instructions for installing Sherlock. It also explains in detail
everything you need to know about initializing Sherlock.
(Optional) Use the SPP application to insert Sherlock macros in your C files
SPP inserts tracing macros to print the values of all arguments to functions and the values returned
from all functions. Refer to the SPP Reference for full details.
Include sl.h in all your source files
SPP can do this for you. Or you can just insert #include "sl.h" in your application’s master
header file. Also, make sure the compile-time constant called SHERLOCK is defined before the
#include "sl.h".
Add code to initialize Sherlock.
The section below called “How to initialize Sherlock” tells how to do this.
Add Sherlock Resources to your application.
The file SL Resources contains resources used by Sherlock. Use ResEdit if necessary to change
the resource ID’s in SL Resources so that they conflict with none of the resources in your
application. If you change resource ID’s in SL Resources you should change the #define
constants at the beginning of the file mac_gui.c.
Create a debugging version of your application.
Compile and link your source files with Sherlock’s support routines. The names of all these
routines are listed in the file called Mac files. Use ResEdit to add the Sherlock resources in SL
Resources to your application. If you forget to add these resources, the Sherlock support routines
will beep and exit during execution of the w_mac_init routine.
Run your program and enable tracing statements.
Enable Sherlock from a simulated command line. The routines in LIBcmnd.c allow you to read
such a command-line easily. The source code for SPP, SDEL and SDIF provide examples.
Create a production version of your application.
After debugging is complete, #undef the SHERLOCK constant and recompile all your source
files. All the code produced by the Sherlock macros will disappear. Relink your program without
the Sherlock support routines to produce a production version of your program.
How to initialize Sherlock
Initialize Sherlock on a Macintosh as follows:
{
char ** argv;
int * argc;
w_mac_init(...)
SL_INIT();
init_args(&argc, &argv, lib_arg_file_name);
SL_PARSE(argc, argv, "++", "--");
arg_do_argv(argc, argv); // optional application function
}
Let's look at each line of this code. First, we declare the argv and argc variables. Sherlock
expects to receive arguments from the command line's argv vector. On the Macintosh the argv
vector does not exist, so the Macintosh version of Sherlock contains the init_args routine that
treats a text file as a simulated command line.
Next, we call w_mac_init. This routine sets up the Sherlock menus and the log window.
w_mac_init can also insert other menus into the menu bar. See below for full details.
Next we call SL_INIT to initialize the Sherlock support routines.
Next we call init_args to read the file specified by lib_arg_file_name. The template file called
LIBlib.c contains a dummy definition for several variables, including lib_arg_file_name. Your
application should create its own version of LIBlib.c, say MyAppLib.c, which contains the name
of a file to use as the simulated command line.
init_args reads the text file, parses it into separate arguments, allocates an argv vector, fills in the
argv vector with pointers to the arguments, and computes the value of argc. The init_args routine
takes three arguments: the address of a pointer to the future argv vector, the address of the argc
value, and the name of the file containing the arguments.
The format of the text file processed by init_args is as follows: Arguments are delimited by white
space, but strings delimited by matching double quote characters are treated as a single argument.
An exclamation mark starts a comment that continues to the end of the file.
Next, we call SL_PARSE to process and remove Sherlock arguments from the argv vector. The
"++" and "--" arguments to SL_PARSE above specify that the prefix ++ enables a Sherlock
argument and the prefix -- disables a Sherlock argument. For example, the two arguments
++a --b would enable tracepoint a and disable tracepoint b.
The function that I have called arg_do_argv is optional. If your application uses command-line
arguments, the place to process those arguments is right after the call to SL_PARSE.
The w_mac_init routine
w_mac_init routine takes 17 parameters which describe your application. This routine creates the
log window used by Sherlock, and can, at your option, install menus. Finally, it can also initialize
the Macintosh ToolBox for you. The following paragraphs discuss each argument in detail.
w_mac_init (
Boolean toolBoxFlag, /* TRUE: Auto Initialize Toolbox. */
Boolean toWindowFlag, /* TRUE: Send output to window. */
char * windowName, /* Name of window. */
Boolean openWindowFlag, /* TRUE: Open window now. */
Boolean addStdMenuFlag, /* TRUE: Insert File and Edit menus. */
Boolean addSlMenuFlag, /* TRUE: Insert Sherlock menu. */
Boolean addAboutFlag, /* TRUE: Add "about" apple menu item. */
char * aboutTitle, /* Title of "about" apple menu item. */
void (*aboutCallBack) (void), /* "about" callback routine. */
Boolean menuBarFlag, /* TRUE: insert added menus now. */
void (*eventCallBack) (void), /* Event loop callback routine. */
void (*dump1CallBack)(void), /* First user callback routine. */
pstring userItem1, /* Menu string for 1st user routine. */
void (*dump2CallBack)(void), /* Second user callback routine. */
pstring userItem2, /* Menu string for 2nd user routine. */
void (*dump3CallBack)(void), /* Third user callback routine. */
pstring userItem3 /* Menu string for 3rd user routine. */
);
toolBoxFlag: When TRUE, w_mac_init initializes the Macintosh Toolbox as follows:
InitGraf( (Ptr) &thePort);
InitFonts();
FlushEvents(everyEvent,0);
InitWindows();
InitMenus();
TEInit();
InitDialogs(0L);
InitCursor();
Warning: Your application must not call any of these routines if toolBoxFlag is TRUE. Sherlock
will crash if toolBoxFlag is FALSE and the application has not already called these initialization
routines. Note that this code does not call MoreMasters or MaxApplZone.
toWindowFlag: When TRUE all Sherlock output (the output produced by the Sherlock macros
themselves as opposed to the output produced inside the macros) is sent to the Sherlock Log
Window. Otherwise, Sherlock output is sent to stdout.
windowName: A C string (not a Pascal string) containing the name of the Sherlock window.
openWindowFlag: When TRUE the Sherlock window remains open after being initialized.
addStdMenuFlag: When TRUE w_mac_init inserts standard Apple, File and Edit menus into
the application’s menu bar. The Apple menu contains an optional “about item” followed by the
usual list desk accessories. The File menu contains only a Quit item. The Edit menu contains the
standard undo, cut, copy, paste and clear items and is highlighted only when a desk accessory is
chosen from the Apple menu. When addSlMenuFlag is TRUE, w_mac_init inserts a Sherlock
menu into the menu bar. Typically this flag would be set to SHERLOCK_DEFINED so that the
Sherlock menu will be installed whenever SHERLOCK is #defined.
addAboutFlag: When TRUE, w_mac_init inserts an “about item” as the first item of the Apple
menu. The aboutTitle and aboutCallBack parameters to w_mac_init are meaningful only when
addAboutFlag is TRUE.
aboutTitle: A C string (not a Pascal string) containing the title of the menu item which is inserted
as the first item of the Apple menu. Command key equivalents are valid in this string. See Inside
Macintosh page I-346 for details.
aboutCallBack: The address of a function to be called whenever the “about item” is selected.
This function must be a void function requiring no arguments. This function should put up a
modal dialog giving the current version and possibly other information about the application.
drawMenuFlag: When TRUE, w_mac_init inserts menus immediately. Otherwise the menus are
inserted (via hidden entry points) the first time the application calls DrawMenuBar.
eventCallBack: The address of a function to be called whenever a line of output is sent to the
Sherlock window. To use the minimal event loop defined in the w_applEvent routine, pass the
address of the following routine as the eventCallBack parameter:
void eventCallBack(void)
{
if (w_applEvent(0) == FALSE) {
es("Program terminated by user.\n");
exit(0);
}
}
dump2CallBack, dump2CallBack and dump3CallBack: The addresses of function to be
called when the one of three “user item” in the Sherlock menu is selected. NULL is valid and
indicates that the indicated user item does not exist.
userItem1, userItem1 and userItem1: Pascal strings (not C strings) containing the titles of
the user items to be inserted into the Sherlock menu. Use a null Pascal string, that is, "\p", for
unused entries.
Adding an Event Loop to your Application
w_applEvent contains a minimal event loop. It handles all events for the Sherlock window and
menu. It returns FALSE if the quit item was chosen from the standard File menu. Applications
with no event loop should call sl_applEvent periodically and regularly. The best way to do this is
to set the eventCallBack parameter to w_mac_init as shown above.
w_applEvent can slow down a program noticeably. skipCount reduces this time overhead by
causing sl_applEvent to execute only once every skipCount times that sl_applEvent is called.
Typically a skipCount of 5 to 20 is appropriate. Making skipCount too small slows down the
application. Making skipCount too large decreases the rate at which events are handled.
Do not call w_applEvent if your application already has an event loop. Instead Sherlock will
update its windows and menus using hidden entry points, defined via macros. See the next
section for details.
Hidden entry points
The following #define’s appear in sl.h. They are used if your application does have an event loop.
In that case, you should not call w_applEvent, nor should you specify an event call back routine in
the call to w_mac_init.
#define GetNextEvent(a,b) w_event(a,b,0L,((RgnHandle)0),0)
#define WaitNextEvent(a,b,c,d) w_event(a,b,c,d,1)
#define MenuSelect(a) w_menuSelect(a)
#define DrawMenuBar w_drawMenuBar
These macros form hidden entry points into the routines in mac_gui.c which maintain the Sherlock
window. Each corresponding entry in mac_gui.c calls the ToolBox routine with the same name as
the macro and performs other tasks as described in the next paragraph.
w_event is the main event loop for the Sherlock code. This routine calls either the GetNextEvent
or WaitNextEvent ToolBox routine, depending on the value of the last parameter. If the returned
event relates to Sherlock, sl_event handles it and returns FALSE, thereby indicating a NULL
event. Otherwise, the event is passed on to the application untouched.
w_menuSelect calls the MenuSelect ToolBox routine, handles any event in the Sherlock menu
and returns false, and passes any events for the application’s menus on to the application.
w_drawMenuBar installs the Sherlock menu in the menu bar and calls the DrawMenuBar
ToolBox routine.